Changelog

This PR introduces several improvements aimed at reducing complexity and increasing flexibility in the codebase:

1. 🔨 Refactor: Reduced Code Duplication:

• Decreased the total number of lines by consolidating overloads into a single Map declaration.
• This approach enhances maintainability and simplifies the addition of new entries.

2. ✨ Feature: Enhanced Type Safety:

• Added a generic type for overriding any other map declared within the hook.
• Ensures that only the specified eventMap generic type is utilized, offering stricter type control and greater adaptability.
• EventTarget Based Implemented add EventTarget support to useEventListener #585 +(useRef or straight DOM Element as config.element argument) + AudioNode...

3. 🔨 Refactor: Parameter Simplification:

• Merged two optional parameters into a single configuration object parameter config .
• Instead of having many optional parameters. This is more readable and scalable.

In Depth Changes

1. 🔨 Refactor: Improved Readability & future refactors (by decreasing code size)

Replaced Overloads with Generic map from Element (string) to [Element, EventMap] tuple + 2 Utility constructs

/** Element as string to Matching EventMap */
type ElementToEventMap = {
   Window: [Window, WindowEventMap]
   HTMLElement: [HTMLElement, HTMLElementEventMap]
   Document: [Document, DocumentEventMap]
   ...

2. ✨ Feature: Enhanced Type Safety

Custom EventMap Generic (overrides all Event to Element Mapping declarations in hook)

useEventListener<{ "user-storage": User }>("user-storage", (updatedUser) => console.log(updatedUser.email))

Globally declared CustomEventMap always available (applied to all DOM Elements, except when custom generic is used)

// globals.d.ts
declare global {
   /** Extends EventMap declarations for all DOM Elements (intersection)*/
   interface CustomEventMap {
      'my-custom-event': CustomEvent<{ isCustom: boolean }>
   }
   /** Intersects EventMap declarations for DOM Window Element (default DOM target for hook listener) */
   interface WindowEventMap {
      'my-custom-event': CustomEvent<{ hash: string }>
   }
}

3. 🔨 Refactor Parameter Simplification

Optional Arguments element?: RefObject<T> & options?: boolean | AddEventListenerOptions moved to single optional Object argument config

const ref = useRef<HTMLDivElement>(null)
const options = { capture: true, once: true }
// 3rd Parameter `config`
useEventListener("mousedown", (value) => console.log(value.pageX), { ref, options })

Adding a new ref Element to Event map

Previously an overload was needed (+6 lines). Now adding a key-value pair to the ElementToEventMap: which value is a tuple containing the element type and its corresponding event map type (+1 line)

Usage Preview

import { useEventListener } from "@/hooks"
import { useRef } from "react"

const App: React.FC = () => {
   const element = useRef<HTMLDivElement>(null)
   const notARefObjectInstance = window // Either ref of a DOM Element or an Element Works

   useEventListener("mousedown", (value) => console.log(value.pageX), { element })
   useEventListener("mousedown", (value) => console.log(value.pageX), { element: notARefObjectInstance  })

   // Custom EventMap Override
   useEventListener<{ "order": { name: string; orderId: number } }>("order", (event) => console.log(event.orderId))

   return (
      <div ref={element} style={{ width: "200px", height: "200px", backgroundColor: "lightblue" }}>
         Click me!
      </div>
   )
}

export default App

• Changeset
• Tests (Passing ✅ )
• Documentation (Updated useEventListener/* 📘 )
• Backwards compatible ❎ (single optionals into congif (element & options) to previous double optional parameters)